Skip to main content

Agentic SWARM Protocol

This guide describes the ValkyrAI SWARM messaging protocol for coordination between:

  • ValkyrAI server workflows
  • ValorIDE agent instances
  • Web-based SageChat sessions
  • ServerConsole processes

Core concepts​

  • Agents are peers with capabilities, state, and a heartbeat
  • Messaging uses WebSocket STOMP with channels for broadcast, direct, and workflow-specific events
  • ACL controls are enforced on every channel

Channel patterns​

Broadcast​

  • /topic/messages
  • /topic/statuses
  • /topic/agents
  • /topic/agent-commands
  • /topic/workflow-monitoring

Private​

  • /user/{principalId}/queue/private
  • /queue/agents/{instanceId}/commands
  • /user/{principalId}/queue/notifications
  • /topic/workflow/{workflowId}

Command endpoints​

  • /app/chat
  • /app/agent/register
  • /app/agent/ack
  • /app/agent/announce

Security model​

  • Authenticated with JWT (Authorization header or ?token=)
  • Private channel ownership enforced by principalId
  • Admin-only channels require ROLE_ADMIN or ROLE_SYSTEM

Message envelope​

{
  "id": "uuid-v4",
  "type": "command|response|broadcast|event|ack|nack",
  "from": { ... },
  "to": { ... },
  "timestamp": "ISO-8601 UTC",
  "ackId": null,
  "payload": {
    "action": "execute|status|query|result",
    "data": {},
    "metadata": {}
  },
  "security": { "signature": "...", "encrypted": false },
  "ttl": 300000,
  "priority": "low|normal|high|urgent"
}

Flows​

1. Agent registration​

  • ValorIDE -> /app/agent/register
  • Server -> /topic/agents broadcast list

2. Command execution (ack+nack)​

  • /queue/agents/{instanceId}/commands for command
  • /app/agent/ack for ack/nack
  • /app/chat for result

3. Workflow coordination​

Workflows trigger agents via ExecModule edges; SWARM telemetry rich context (workflowId, correlationId).

Actionable sections​

  1. Implement new agent feature: publish on /topic/agents and watch /topic/statuses
  2. Add endpoint agent/heartbeat to refresh lastSeen state
  3. Use workflow-state metadata for traceability in telemetry dashboards

Adoption in code​

  • ValkyrAI backend: SwarmRegistryService, MothershipService
  • Frontend: /src/components/Swarm/, useSwarmAgents hooks
  • ValorIDE: integration on agent project + mcp channel adapters